Skip to content

Packages refresh#4408

Draft
seangrate wants to merge 8 commits into
Macaulay2:developmentfrom
seangrate:packages
Draft

Packages refresh#4408
seangrate wants to merge 8 commits into
Macaulay2:developmentfrom
seangrate:packages

Conversation

@seangrate

Copy link
Copy Markdown
Member

(This is from the ideas discussed in the Packages group (@seangrate, @dmaclagan, @wilvalin, and @foschreyer) at the M2@GT 2026 workshop)

This pull request comprises two main changes to the package infrastructure:

  1. In the documentation, the order of sections on the landing page for a package (the top-level node of the package) has been revised (see PackageFrontpage.pdf).
  2. The options for newPackage have some additions and changes:
    • Date is now LastUpdated to make its purpose clearer (original release date versus date of version release)
    • A new Maintainer option to ensure packages have a designated person in charge of maintenance, especially needed whenever a package's authors are, for instance, no longer in academia.
    • The Maintainer and Authors now have Orcid as an available field which takes in the Orcid as a string
    • The Keywords option has changed meaning
      • Areas replaces the original Keywords intention; e.g., Areas = {"Combinatorics"}
      • Keywords is now intended for more fine-grained identifiers like "Betti numbers" or "toric varieties" (think arXiv keywords)
    • Two classification system options have been added
    • The Abstract option has been added. This is intended for a future feature for better package browsing.

Here is an example using the new options:

newPackage("SamplePackage",
    AuxiliaryFiles => false,
    Version => "1.0",
    LastUpdated => "June 3, 2026",
    Maintainer => {Name => "Sean Grate",
                   Email => "sgrate@iastate.edu",
                   HomePage => "https://seangrate.com",
                   Orcid => "0000-0003-0151-2158"},
    Authors => {{Name => "Sean Grate",
                 Email => "sgrate@iastate.edu",
                 HomePage => "https://seangrate.com",
                 Orcid => "0000-0003-0151-2158"},
                {Name => "Diane Maclagan"},
                {Name => "Kalina Mincheva"},
                {Name => "Frank-Olaf Schreyer"}},
    Headline => "combinatorial algorithms",
    Abstract => "This is some abstract with a sentence or two written. No wonder it so long, but also a bit short.",
    Areas => {"Combinatorics"},
    MathematicsSubjectClassification => {"05B25"},
    ComputingClassificationSystem => {"Mathematics of computing" => {"Discrete mathematics" => {"Combinatorics" => "Combinatorial algorithms"}}},
    Keywords => {"matroids", "combinatorial optimization"},
    HomePage => "https://somewebsite.com",
    PackageImports => {"Complexes"},
    PackageExports => {"Graphs", "Posets"},
    Certification => {
         "journal name" => "The Journal of Software for Algebra and Geometry",
         "journal URI" => "https://msp.org/jsag/",
         "article title" => "SomePackage: a Macaulay2 package",
         "acceptance date" => "04 July 2025",
         "published article URI" => "https://msp.org/jsag/2025/7-2/p03.xhtml",
         "published article DOI" => "10.2140/jsag.2025.7.04",
         "published code URI" => "https://msp.org/jsag/2025/7-2/jsag-v11-n1-x03-SomePackage.m2",
         "release at publication" => "cf37f5a1eefc2fe7e6eef2868718256106805027",
         "version at publication" => "1.0",
         "volume number" => "11",
         "volume URI" => "https://msp.org/jsag/2025/7-2/"
    }
)

All existing packages have had their newPackage header changed to comply with these revisions.

@d-torrance d-torrance added M2@GT26 Project from the "Future of Macaulay2" workshop at Georgia Tech in May 2026 update to existing package(s) labels Jun 4, 2026

@d-torrance d-torrance left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A number of conflicts to fix. (Sorry -- like half of them are me updating my email address!)

@seangrate

Copy link
Copy Markdown
Member Author

I should note: All references in the Macaulay2 documentation and on the wiki for package writing still need to be updated to reflect these changes.

@d-torrance d-torrance left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are a few newer packages in development that haven't gotten the changes, e.g:

../../../../../Macaulay2/m2/option.m2:17:26:(1):[67]: error: encountered an unknown key or option: Date
../../../../../Macaulay2/packages/EuclideanDistanceDegree.m2:1:10:(2):[66]: --back trace--

CacheExampleOutput => null,
Certification => null,
Configuration => {},
Date => null,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removing the key Date would cause all existing packages out there to produce an error when loaded. I'm also leaning against this change in general though because I prefer simple key names, but with clear documentation of what they should contain elsewhere.

@mahrud mahrud Jun 4, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The same for Keywords, actually. Nevermind, you're not removing it so it's not gonna cause errors. I like Areas.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You probably didn't mean to include this.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And several files in MergeTeX.

InfoDirSection => "Macaulay2 and its packages",
Keywords => {},
Maintainer => null,
MathematicsSubjectClassification => {},

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of adding both MathematicsSubjectClassification and ComputingClassificationSystem, how about adding a unifying SubjectClass key and adding functions like MSC(ZZ,List) and CSS(ZZ,List) or similar? e.g. SubjectClass => {MSC(2020,{"13D02","14M25"}, ACM(...)}.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is ok if we're leaving MSC as optional. If we want to make it compulsory (which I think is a good idea - this would be a good thing to be able to search by when we have the package table online) then I wouldn't put them on the same footing. Is there a large group of users who would prefer the ACM classification? (this was mentioned in passing in the summary session, but not discussed).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

M2@GT26 Project from the "Future of Macaulay2" workshop at Georgia Tech in May 2026 update to existing package(s)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants